Mac Magazin/MacEasy 42/Mac Magazin and MacEasy Magazine CD - Issue 42.iso/Software/Utilities/Sonstige/Menu Grabber 1.3.1/Menu Grabber Help (text)

Text File | 1998-01-07 | 22.6 KB | 579 lines | [TEXT/R*ch]

Menu Grabber 1.3.1

December 4, 1997



Disclaimer and Copyright Notice


Menu Grabber is a free utility which uses the Menu Events extension to
control other applications through their menus.  The author, Ross Brown,
makes no warranty, either express or implied, with respect to this
software, its performance, merchantability, or suitability for any
particular purpose.  People using the Menu Grabber utility do so at their
own risk.  The author disclaims all liability for loss of data, mechanical
damage, or other losses suffered while using the Menu Grabber utility.

Menu Grabber is an AWOL Software Production, Copyright © 1994-7
Ross Brown.  All rights reserved.  Permission is granted to make and
distribute copies of this software, provided this disclaimer and copyright
notice are preserved on all copies.  The software may not, however, be
sold or distributed for profit, or included with other software which is
sold or distributed for profit, without the permission of the author.

There are no site license fees for the use of Menu Grabber within an
organization.  The author encourages you to make and distribute as many
copies of the application as you wish, for whomever you wish, as long as
it is not for profit.  Menu Grabber is part of a set of cooperating
programs, AWOL Utilities.  The tutorial help you are reading is designed
for handling by the help server application Help on Wheels, which is also
part of AWOL Utilities.



Distribution Policy


New versions of individual AWOL Utilities programs, including Menu
Grabber, are available by anonymous FTP from popular archive sites
including <ftp://sumex-aim.stanford.edu/info-mac/> and its various
mirror sites, such as <ftp://mirrors.aol.com/pub/info-mac/>.

For the latest information about AWOL software, including AWOL Utilities,
please visit the AWOL Web page at <http://www.magma.ca/~awolsp/>.

Support for AWOL Utilities is through Internet mail at
<mailto:[e-mail]>.  The software is not available by
FTP from this site.  The address for paper correspondence is AWOL
Software Productions, PO Box 24207, Hazeldean RPO, Kanata, Ontario,
Canada K2M 2C3.

Macintosh users who do not have access to electronic sources of free and
shareware software may obtain a copy of AWOL Utilities by sending a
self-addressed stamped envelope and an 800K (or larger) formatted
diskette to the author at the above address.  U.S. users are reminded that
postage from Canada in 1997 is C$0.52 up to 30 grams (1 oz.), C$0.77 up
to 50 grams (1 3/4 oz.), and C$1.17 up to 100 grams (3 1/2 oz.).
US$0.50, US$0.75, and US$1.00 in coin is acceptable in place of stamps
for the respective weights.  People outside the U.S. and Canada may send
an international postal reply coupon instead of Canadian stamps (available
from any post office).  Please use sturdy envelopes, preferably cardboard
disk mailers.  (Mailers over 5 mm (1/5") thick require C$1.17 postage to
the U.S.)
Please do not send return envelopes with non-Canadian
stamps, as Canada Post will not accept them.



About AWOL Software Productions


AWOL Software Productions specializes in custom development of
software for the Mac OS.  Since its inception in 1990, AWOL has
developed a number of programs which enhance the Mac OS user
experience, working in nearly every part of the Macintosh Toolbox.  If
you have a short-term programming task or product idea but lack the
staff to do the expert design, coding, and documentation, we invite your
inquiry.

Virtual Desktop is AWOL’s best-known effort, serving the desktop
expansion needs of thousands of Mac users around the world.  Later in
1997, AWOL will release a new commercial version 2.0 to replace the
freeware version contained in the AWOL Utilities package.  Please contact
us at <mailto:[e-mail]> for feature and ordering
information.

Users who want more out of the Mac’s speech capabilities should check
out MacYack Pro, a jointly developed package of speech tools marketed by
Scantron Quality Computers (<http://www.lowtek.com/macyack/>;
<mailto:[e-mail]>; 20200 Nine Mile Rd., St. Clair Shores, MI
48080).



Purpose


As its name suggests, Menu Grabber reaches out to another application
and grabs a copy of its menu bar.  When you select an item from a grabbed
menu, or press its Command-key equivalent, Menu Grabber sends a
“Menu event” to the target application, simulating a menu selection in
that application.

The target application can be on your machine or on any machine on your
AppleTalk network, but it must be a machine equipped with the Menu
Events extension.  Any “high-level-event-aware” application (one that
supports program linking) can be a target, even if it is not designed to be
scriptable.  With some limitations, Menu Grabber gives you a way to
control applications on other machines which you would not otherwise
have.

NOTE:  The help file for the Menu Events extension contains a complete
description of the extension, the Apple events which it supports, and
some usage suggestions for programmers.



Who Can Use Menu Grabber?


Any Macintosh running System 7.0 or later can use Menu Grabber.
Because it’s an application, and not a system extension, it shouldn’t
conflict with your other programs.

It is not necessary to have the Menu Events extension installed on the
machine where you use Menu Grabber to target applications on another
machine.

Menu Grabber can be placed on an AppleShare file server, where any
number of users can access it simultaneously.



How Does Menu Grabber Work?


About Menu Events

When the Menu Events extension is installed on a Macintosh, all
high-level-event-aware applications running on that machine gain support
for Menu events.  Menu events are a class of Apple events which allow a
sender to query an application’s menus and menu items, and to select its
menu items.  (See the help file for the Menu Events extension to learn
more about the Apple event syntax for Menu events.)

In order for Menu events to work across an AppleTalk network, the target
machine and application must meet the following conditions:
•  program linking started in Sharing Setup control panel
•  program linking allowed to user or guest through Users & Groups
control panel
•  remote program linking allowed through application’s Sharing dialog
•  Menu Events extension installed

NOTE (technical, but important):  Even with remote program linking
allowed, most applications run in a mode where they will not permit user
interaction in response to an event from another machine.  Menu Events
always requests user interaction to make the target application active, as
it would normally be when it senses a menu selection.  Menu Events is
programmed to overcome this problem.  If you want to allow remote Menu
events (such as sent by Menu Grabber) to work on applications running in
the default kAEInteractWithLocal interaction mode, leave Menu Events
unlocked.  Otherwise, lock it using the Get Info dialog, so that applications
can decide for themselves whether to allow remote control.  This choice
does not affect the acceptance of Menu events by applications which are
running in the kAEInteractWithSelf (always reject) or kAEInteractWithAll
(always accept) interaction mode.

After installing the Menu Events extension on the target machine, you
must restart that machine to enable support for Menu events.  An icon
appears at startup to confirm that the extension has initialized
successfully.  The icon includes a little padlock if Menu Events has been
locked against remote senders.


Selecting a Target Application

Once you have installed the Menu Events extension on the target machine,
you are ready to try Menu Grabber.  You may decide to run Menu Grabber
on the same machine, as a first test, but to be certain that Menu events
will work for a certain target application across the network, you should
also try grabbing its menus from another machine.

To grab an application’s menus, click the Grab… button in the Menu
Grabber dialog, then select the zone, machine, and application you want.
If the machine’s name does not appear, check that it is connected to the
network, and that program linking is started.  If the application’s name
does not appear, check that it is open, and that remote program linking is
allowed in its Sharing dialog.  If you have to turn on remote program
linking, you must quit the application first.  If the check box remains
grayed out after quitting the application, and the application is neither
locked nor on an unwritable volume, it is likely that the application is not
high-level-event-aware — in other words, it doesn’t support program
linking, and can’t be controlled by Menu Grabber.

Unfortunately, some applications, such as any version of Finder which
predates Power Macintosh (version 7.1.2), are programmed in such a
way as to ignore high-level events which they do not understand, such as
Menu events.  If it seems to be taking a long time to grab the application’s
menus, you can wait 30 seconds for the attempt to time out, or press
Command-Period to cancel the attempt.  A few other applications
(Microsoft’s, especially) actively prevent system event handlers from
working; you will recognize them by the error message, “The target
application has prevented the usual handling of the Menu event.  Menu
events should not be used with this application.”

If all goes well, the Menu Grabber dialog changes to show that it has
grabbed the application’s menus, and the menu bar changes to match.  If
you are using a color display, the menu bar turns red, and all grabbed
menus have white titles, to make it obvious that these are not Menu
Grabber’s own menus.

Some applications portray their menus differently depending on whether
or not you press modifier keys (Shift, Control, Option, Command) when
you click in the menu bar.  Any modifier keys you press while clicking the
Grab… button are applied when grabbing the target application’s menus,
and also when you select items from the grabbed menus.  The dialog shows
which modifiers are in effect.

To select another application, repeat the procedure.  To refresh your
view of the target application’s menus, click the Refresh button, with or
without modifier keys.  To revert to Menu Grabber’s own menus, click the
Revert button, or press Escape or Command-Period.


Using Grabbed Menus

Having grabbed the menus of a target application, you can control that
application by pulling down menus and selecting menu items from within
Menu Grabber.  If you have pressed any modifier keys (Shift, Control,
Option, Command), and the target machine is running Menu Events version
1.1.2 or later, these modifiers are applied to the menu selection, along
with any modifiers which were pressed when the menus were grabbed.
Meanwhile, the target application and its menus continue to work as usual.

Menu Grabber faithfully reproduces standard hierarchical (cascade)
menus, Command-key shortcut equivalents, bullets and check marks, and
styles such as underlining and italics.  It does not reproduce icons
attached to menu items.  If it encounters a non-standard menu (one which
uses a menu definition procedure other than the classic or
Appearance-compliant standard 'MDEF'), it substitutes a menu containing
a grayed-out item saying “non-standard menu,” because Menu Grabber
does not have access to that function.  If a menu is unavailable for any
reason, you will see a similar “unavailable menu” indication.  Keyboard,
Help, and Application menus are never grabbed; selecting an item from
these menus does not cause a Menu event to be sent to the target
application.

Menu Grabber adds an extra disabled item to the bottom of each grabbed
menu, to show the menu ID.  This may help you if you are writing a
program or script to send a Menu event to the application.

The reproduction of the target application’s menu bar is static.  If you
need to bring it up to date, because menus may have been added or
deleted, or items enabled or disabled, you must refresh the menu bar by
clicking the Refresh button.



Suggestions for Use


Menu Grabber is distributed as part of a free set of cooperating
programs, AWOL Utilities.  This section explains how Menu Grabber can
work in conjunction with the other programs.


Help on Wheels

Help on Wheels is an efficient and full-featured help server which displays
help files on behalf of client applications.  The help file you are reading is
distributed alongside the Menu Grabber application file as a separate Help
on Wheels document.

You can read this help at any time while using Menu Grabber, either by
selecting “Menu Grabber Help” from the Help menu, or by pressing the
Help or Command-? key.  This version of Menu Grabber has some support
for the sophisticated features of Help on Wheels, such as
context-sensitivity, casual displays, and “hot” hypertext buttons.



Dialogs


Menu Grabber has one dialog, to show its status.


The Status Dialog

This dialog is present at all times while Menu Grabber is running.  When it
is asking you to click a button to select a target application, it is operating
under its own menus.

When you have selected a target application, and Menu Grabber is trying
to grab its menus, the dialog suggests that you can press Command-Period
to cancel the attempt.  Across a network, it may take up to 15 seconds to
grab an application’s menus; some applications may never respond.  Menu
Grabber will wait 30 seconds before giving up.

When it has grabbed an application’s menus, the dialog shows which
application.

NOTE:  To quit Menu Grabber, you can click the close box, or revert to
Menu Grabber’s own menus, then select Quit from the File menu or press
Command-Q.  If you press Command-Q while grabbing, you will probably
cause the target application to quit, not Menu Grabber!

•  Grab…

Click here to bring up the program selection dialog, so that you can select
an application for menu grabbing.  If you are currently grabbing an
application’s menus, this releases them.  Pressing the Return or Enter key
is equivalent.

•  Refresh

Click here to refresh your view of the target application’s menus.  This
button is not available when Menu Grabber is operating under its own
menus.

•  Revert

Click here to revert to Menu Grabber’s own menus, releasing those
previously grabbed.  This button is not available when Menu Grabber is
operating under its own menus.  Pressing the Escape or Command-Period
key is equivalent.


The About Dialog

This dialog presents Menu Grabber’s About box.  It is opened by the
“About Menu Grabber…” command in the Apple menu.

It mentions, by way of a balloon, that Menu Grabber offers help through
both Balloon Help and Help on Wheels.  If you already have balloons
showing, Menu Grabber spares you the balloon, figuring that you’ve
probably seen enough recently.



Menus


This section describes each of Menu Grabber’s menus.

On a color display, when Menu Grabber is grabbing the menu bar of
another application, its menu bar turns red to warn you that any menu
action will affect that application.  Grabbed menus have white titles and
white-on-black items, as shown in the picture above.  (NOTE:  The Mac OS
8.0 Appearance Extension prevents Menu Grabber from presenting the
menu items in white-on-black.)  The Keyboard, Help, and Application
menus are not affected by grabbing, and retain their usual colors.

Menu Grabber adds an extra disabled item to the bottom of each grabbed
menu, to show the menu ID.

The rest of this section describes the menus which appear before you
first grab an application’s menus, or after you revert.  At other times,
when you are grabbing, these menus are not available, except for the Help
menu, which never changes.


The Apple Menu

•  About Menu Grabber…

This command opens Menu Grabber’s About dialog, which invites you to
try Balloon Help or Help on Wheels to learn more about Menu Grabber.


The File Menu

•  Quit (Command-Q)

This command quits Menu Grabber.


The Edit Menu

•  Undo (Command-Z)

This command is not used by Menu Grabber.  It is present only for desk
accessories.

•  Cut (Command-X)

This command cuts selected text to the clipboard.  It is used only with
desk accessories.

•  Copy (Command-C)

This command copies selected text to the clipboard.  It is used only with
desk accessories.

•  Paste (Command-V)

This command inserts the contents of the clipboard at the current cursor
location or replaces the currently selected text by the contents of the
clipboard.  It is used only with desk accessories.

•  Clear

This command clears the selected text in a desk accessory.


The Help Menu

•  About Balloon Help…

This command, supplied by System software, tells you how to use Balloon
Help.  Menu Grabber supports Balloon Help.

•  Show/Hide Balloons

This command, supplied by System software, lets you turn Balloon Help
on and off.  Menu Grabber supports Balloon Help.

•  Menu Grabber Help

This command asks Help on Wheels to display Menu Grabber’s help file.
This will start the help server if it was not already running.  If the help
server cannot be found on any mounted volume, Menu Grabber will offer
to save a readable copy of the help file as a TeachText file, then ask
Finder to open the file.  If the help file is missing or invalid, this command
is disabled.

Pressing the Help or Command-? key at any time does the same thing.
When there is a modal dialog box on your screen, the menu command is
disabled, and the keyboard is the only way to display help.



Limitations


Menu Grabber inherits the limitations of the Menu Events extension.  Menu
events work only if the target application is programmed according to the
customary rules about handling of high-level events and reacting to clicks
in the menu bar.  Some of the big-name applications are among the
exceptions to these standards, including Finder 7.0 or 7.1 (totally
unwilling, but fortunately it has its own suite of Apple events; 7.1.2 or
later will work), ResEdit 2.1.1 (nothing good to say about its Apple event
handling), and most Microsoft applications (they install a handler over all
Apple event classes, which doesn’t return errAEEventNotHandled when
it’s supposed to).

If the menu item you select brings up a dialog box, that dialog will be on
the target machine, so if that machine is unattended, you may have a
problem.

If the target machine is under the influence of a screen saver or security
package which would present a modal dialog in response to a mouse click,
then you will not be able to grab menus.  The same is true if the target
machine is already showing a modal dialog, preventing Menu Events from
activating the target application.

Menu Grabber presumes that all hierarchical (cascade) menus are
standard, so they may sometimes look odd.

If you are also using the help server Help on Wheels, you should read the
Menu Events help file for information about a conflict between the two
which can cause the target application to hang.

Any application, such as Finder 8.0, which yields time to other
applications after a menu item is selected, may find itself in the
background while handling that selection.  This may cause odd results,
such as the application blinking its icon in the Application menu to request
user interaction before presenting a modal dialog box.



Programmer Notes


If you are interested in scripting, you should find out how to use Menu
events to control non-scriptable applications through their menus, making
them scriptable and recordable.  The Menu Events distribution includes a
scripting addition ('osax') and a sample script to get you started.

The Menu Events extension, by itself, can support Menu events without
any scripting package.

Write to the author at the above address if you want to know more about
the Menu Events extension or how Menu Grabber was programmed.



Acknowledgements


Thanks to C.K. Haun and the other folks at Apple Developer Technical
Support who put together those clever little code snippets which give
folks like me such odd ideas.

One big hug to Toni and the family for enduring a LOT of late nights.

Special thanks to the 170 fine people who beta-tested this software, and
to others who provided useful information.



Revision History


1.3.1 (December 4, 1997)
•  Public AWOL Utilities 1.4 release.
•  Menu Grabber now supports the new Mac OS 8 platinum appearance.
However, the Appearance Extension prevents Menu Grabber from
presenting the menu items of grabbed menus in white-on-black.
•  Menu Grabber now recognizes the new Appearance-compliant standard
'MDEF' as well as the classic standard 'MDEF', so that you can capture the
menus of Appearance-compliant applications such as Finder 8.0.

1.3 (March 6, 1996)
•  Public AWOL Utilities 1.3 release.
•  Added support for modifier keys pressed while grabbing menus, so that
you can see menu items in their alternate form.  These modifiers are also
applied when you select items from the grabbed menus.  The dialog shows
which modifiers are in effect.
•  Added the Refresh button to make it easier to work continuously with
the same target application.
•  Fixed a memory leak which could cause Menu Grabber to crash after a
large number of grabs.

1.2 (October 17, 1994)
•  Public AWOL Utilities 1.2 release.
•  Corrected a conflict with the MenuChoice utility which caused a failure
to grab menus.
•  Made Menu Grabber compatible with versions of Menu Events prior to
1.1.2.
•  Improved the message given when the target application cannot be
found.
•  Improved handling of programs listed in the program selection dialog
which are not applications.

1.1.2 (April 19, 1994)
•  Modifier keys (Shift, Control, Option, Command) are now effective on
every menu selection where the target machine has Menu Events version
1.1.2 or later.
•  Changed handling of non-standard menus to accommodate revisions in
Menu Events version 1.1.2.

1.1.1 (April 11, 1994)
•  Document addition of scripting files to Menu Events 1.1.1 distribution.

1.1 (March 28, 1994)
•  Public AWOL Utilities 1.1 release.
•  Corrected a bug which could cause the Grab… button to become
unavailable.
•  Documented that Menu Grabber works with Finder 7.1.2.

1.0.6 (March 13, 1994)
•  Some minor documentation changes.
•  Added the thank-you hot button under Acknowledgements.

1.0.5 (February 27, 1994)
•  Corrected an incompatibility with SpeedyFinder7’s Help menu removal
option which prevented help display.
•  “Trying to grab” message now suggests Command-Period to cancel.
•  Allowed the application to operate without a preferences file (for
example, when startup disk is locked).

1.0.4 (February 6, 1994)
•  Removed mention of Menu Events bug fixed in version 1.0.5.

1.0.3 (February 1, 1994)
•  Changed color of Menu Grabber menu bar and menu titles when
grabbing, to warn user that any menu action will affect another
application.

1.0.2 (January 11, 1994)
•  Removed mention of Menu Events bug fixed in version 1.0.2.
•  Added disabled “menu ID #” items to grabbed menus, to help users who
want to script Menu events.

1.0.1 (December 31, 1993)
•  Initial AWOL Utilities 1.0.1 release.